docs: Runtime support section — Node vs Cloudflare Workers#9
Merged
Conversation
safeFetch resolves targets with node:dns lookup, which Workers' nodejs_compat implements as a 'Not implemented' throw (only the resolve* family works, via DoH) — and Workers fetch does its own internal resolution, so userland cannot pin a checked IP to the socket. The README implied safeFetch was universal; consumers deploying to Workers found out at runtime. New section documents the support matrix (pure URL/policy/tool-input checks work everywhere; safeFetch and undici pinning are Node-only), explains why the gap is unclosable from inside a Worker, and shows the two recommended Workers patterns: a manual-redirect loop with per-hop validateUrl + strict allowlist (with the derive-the-allowlist- from-the-submitted-URL variant for own-site crawling), and a Node egress service with pinDns: true for genuinely arbitrary fetches. Also brings README.ko.md up to parity with 0.3.0's English README — the safeFetch redirect-hardening description and the DNS pinning subsection had not been mirrored. Tests: 124/124 green (docs-only change).
This was referenced Jul 12, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The README implied
safeFetchworks everywhere. It doesn't: it resolves targets withnode:dnslookup, which Cloudflare Workers'nodejs_compatimplements as a "Not implemented" throw (only theresolve*family works, via DoH) — and Workersfetchperforms its own internal resolution, so userland can't pin a checked IP to the socket. Consumers deploying to Workers found out at runtime.New section
Runtime support: Node vs Cloudflare Workers (both languages):
validateUrl/UrlPolicy/HostPolicy/guardToolInput*are pure and work everywhere;safeFetch+undiciDNS pinning are Node-only.fetch(redirect: 'manual')with per-hopvalidateUrland a strict allowlist, including the derive-the-allowlist-from-the-submitted-URL variant for "crawl the customer's own site" flows.safeFetchwithpinDns: truefor genuinely arbitrary URL fetching.Also
README.ko.mdwas behind 0.3.0's English README — the redirect-hardening description and the DNS pinning subsection were never mirrored. Brought to parity.Verification
Docs-only; test suite still green locally (124/124).
Context
First consumer of this guidance is AskLinq's URL ingestion (Workers runtime) — linq-kit roadmap Phase 1.5 flagged this exact doc gap.